=========================================================================
ISTRUZIONI per il SECONDO FRAMMENTO del PROGETTO di LSO12/13
========================================================================

Il progetto BRIS e' suddiviso in  tre frammenti.
Il secondo e' descritto in questo README.

Questo frammento prevede la realizzazione di:

1) bristat: uno script per elaborare le statistiche su vittorie e sconfitte 
           dai file di log

2) comsock.c : una libreria di comunicazione basata su socket AF_UNIX

3) brsserver e brsclient: che realizzano una versione iniziale del
server per il gioco della briscola (implementando solo la
funzionalita' di registrazione "-r" e cancellazione utenti "-c" ed il
checkpointing -- richiesto dal segnale SIGUSR1) 

------------------------------------------------
Estrarre il materiale dal KIT 
------------------------------------------------
Creare una directory temporanea, copiare lsokit_f2BRIS.tar   
nella directory e spostarsi nella directory appena creata. Es.

$$ mkdir Frammento2
$$ mv lsokit_f2BRIS.tar Frammento2
$$ cd Frammento2

S-tarare i file del kit

$$ tar xvf lsokit_f2BRIS.tar 
questa operazione crea nella directory corrente una directory "BRIS" che
contiene:

$$ ls BRIS
doc/ src/ README bris1213.pdf

src/ contiene sorgenti, header, Makefile test etc
doc/ contiene i file per la documentazione doxygen

README spiega la struttura complessiva

Le specifiche per la realizzazione complessiva del progetto
si trovano nel file bris1213.pdf

========================================================================
ISTRUZIONI per la realizzazione 
========================================================================

-----------------------------------------------
Descrizione dei file in src/
-----------------------------------------------

README-2		: questo file

Makefile		: makefile per il test finale dei primi 2 frammenti e la
			  consegna  
			  (NON MODIFICARE se non nelle parti richieste)

testbristat		  : script di test

DATA/*.log
DATA/out.bristat.check
DATA/out.cli.check
DATA/brs.checkpoint.check
		:     file di dati ed output attesi per i test
			   (NON MODIFICARE)

comsock.h       : tipi e prototipi delle funzioni da realizzare
			  per la libreria di interazione
			  (modificare solo aggiungendo
			  campi/definizioni/prototipi senza MODIFICARE/ELIMINARE
			  quelli gia' esistenti)

testserv.c
testcli.c
			: programmi c per il test della libreria di 
			  comunicazione
			(NON MODIFICARE)

testseq 		: script bash di test del server e del client riguardo 
			alle funzionalita' "-c", "-r" e scrittura su file di 
			checkpoint (scatenata da SIGUSR1)
                          (NON MODIFICARE)

newMazzo_r_x86_64.o     
newMazzo_r_x86.o	: impementazione thread safe della newMazzo (serve per il corretto funzionamento del Makefile e verra' usata nel terzo frammento)
			(NON MODIFICARE)

------------------------------------------------
Cosa deve essere realizzato: 1) script bristat
------------------------------------------------

Lo script bristat elabora off-line i file di log generati da brsserver
ed elabora varie statistiche. Le specifiche del comportamento dello
script si trovano nella Sezione specifica del file bris1213.pdf. 

----------------------------------------------------------------------------
Apertura, chiusura e lettura di file in BASH
----------------------------------------------------------------------------
L'apertura e la chiusura di un file puo' essere effettuata in bash attreverso
la 'exec' in particolare:

   exec n< file_name    

apre il file file_name in lettura e gli assegna il file descriptor 'n' 

   exec n> file_name

apre il file file_name in scrittura (file descriptor n)

   exec n<> file_name

apre in lettura e scrittura. Invece per chiudere il file descriptor n

   exec n>&-

Dopo aver aperto il file e' possibile leggerlo utilizzando il comando 'read'
con opzione -u numero_descrittore.


------------------------------------------------
Cosa deve essere realizzato: 2) la liberia comsock 
------------------------------------------------

Deve essere realizzata una libreria di comunicazione via 
socket AF_UNIX il cui header e' specificato in 

src/comsock.h

Tale file contiene i prototipi delle funzioni da
realizzare, i tipi di dato e le define relative ai messaggi scambiati 
nel protocollo usato fra client e server.

E' possibile generare la documentazione doxygen per questo file invocando

  bash:~$ make docu

nella directory src/ dopo l'esecuzione visualizzare 

../doc/html/index.html

con un qualsiasi browser.

Il Makefile deve essere esteso con un opportuno target per comsock.o.

------------------------------------------------
Cosa deve essere realizzato: 3) versione preliminare del brsserver e 
                                del brsclient
------------------------------------------------

Si devono realizzare il srever ed il client relativamente alle
funzioni di registrazione e cancellazione utenti ed all funzionalita'
di checkpointing richiesta dal segnale SIGUSR1 (vedi bris1213.pdf).

Il Makefile deve essere esteso con opportuni target per la
compilazione e la generazione degli eseguibili brsserver e brsclient 
e dei moduli oggetto (file *.o).

------------------
Come procedere :
-----------------

0) leggere attentamente questo README 

1) analizzare accuratamente i file di input (*log*) e
   l'ouput atteso (out*) 

2.1) implementare lo script bristat con le opportune sottofunzioni in un file
   './bristat' nella directory BRIS/src
   testando incrementalmente il codice prodotto

2.2) testare lo script con 

       bash:~$ make test21

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory BRIS/src
  (2) E' importante che il test venga effettuato solo su uno script 
  gia' ragionevolmente corretto  altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.

3.1) implementare le funzioni richieste in comsock.h
   testando incrementalmente il codice prodotto

3.2) testate la libreria con 

  bash:~$ make test22

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory BRIS/src
  (2) E' importante che il test venga effettuato solo su una libreria
  gia' ragionevolmente corretta  altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.

4.1) implementare il server ed il client relativamente alle
   funzionalita' richieste testando incrementalmente il codice prodotto

4.2) testare client e server con

  bash:~$ make test23

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory BRIS/src
  (2) E' importante che il test venga effettuato solo su una libreria
  gia' ragionevolmente corretta  altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.


5) preparare la documentazione: ovvero commentare adeguatamente il file che
   contiene la soluzione aggiungendo la dichiarazione di originalita'

   # \file bristat
   # \author Giuseppe Verdi
   #  Si dichiara che il contenuto di questo file e' in ogni sua parte opera
   #  originale dell' autore. 
 
   /** \file pippo.c
       \author Giuseppe Verdi
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale dell' autore.  */

     Non e' richiesto di preparare anche la documentazione formato
     doxygen. Chi volesse farlo e' invitato a leggere il  README.doxigen
     del primo frammento.


6) copiare il file "gruppo.txt" (con nome e dati fornito nei frammenti
   precedenti) e "gruppo-check.pl" all'interno della directory src/

7) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna2

   e seguendo le istruzioni. 

   Tutte le consegne verranno confermate con un messaggio di reply
   all'indirizzo da cui e' stato inviato il tar entro 2/3
   giorni. In caso questo non si verifichi contattare il docente.
   
---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non contenenti un tar creato da
   "make consegna2" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborati coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   IN CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO IN CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.

----------------------------
 VALUTAZIONE DELL'ESERCIZIO:
----------------------------

Gli studenti che consegnano una versione funzionante e ragionevolmente
corretta  entro la data di scadenza prevista su WEB
accumulano un bonus di 2 punti che verra' sommato al voto finale (vedi
lucidi lezioni ed esercitazioni).

La qualita' del codice consegnato verra' valutata come
parte del progetto finale e contribuira' alla votazione assegnata al progetto.
Eventuali caratteristiche in piu' rispetto a quelle strettamente richieste
dalle specifiche date verranno valutate in questa sede.
